home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / msdos / get26upd.zip / GET26NEW.DOC < prev    next >
Text File  |  1993-12-24  |  44KB  |  889 lines
  1.  
  2.   GET26NEW.DOC - New features in GET.EXE 2.6 - Copyright 1993 Bob Stephan
  3.  
  4.   This file summarizes the new and improved features in GET.EXE Version
  5.   2.6. If you have been using an older version of GET, read this
  6.   file to find out what has been changed, and what has been added.  
  7.  
  8.   The file you obtained should be GET26UPD.ZIP.  It is an upgrade
  9.   version of Bob Stephan's BATch Enhancer, GET.EXE, Version 2.6.  It 
  10.   is not authorized to be used except in conjunction with the documen-
  11.   tation included with the previous release, GET.EXE Version 2.5.  
  12.   All warranty and licensing provisions in the documention for Version
  13.   2.5 apply to Version 2.6 except as modified herein.  The new features
  14.   in this version were selected because they were requested by users.
  15.  
  16.   GET Version 2.6 is distributed as GET26.EXE so as to not inadvertently 
  17.   overwrite previous versions.  Rename GET26.EXE to GET.EXE when you are 
  18.   ready to replace older versions.
  19.  
  20.   Pricing, licensing, and copyright.
  21.   ---------------------------------------------------------------
  22.   GET 2.6 is released as shareware with a requested registration fee of 
  23.   $15 plus $1 shipping and handling to U.S.A, Canada, or Mexico, or $3
  24.   to other foreign countries. GET26UPD is released as an upgrade with no
  25.   manual included in the shareware package other than the information in
  26.   this file.  Registered license holders of GET 2.5 are eligible to receive 
  27.   a registered copy of the 2.6 upgrade FREE with an option to buy the 
  28.   full 2.6 manual for $6+S&H when available. The full manual which we
  29.   intend to have commercially printed can be included with new 
  30.   registrations for $6 or ordered later by registered users for $6 plus 
  31.   S&H as above.  These prices are subject to change.  Unfortunately, 
  32.   economics preclude us from continuing the free upgrade policy from
  33.   Version 2.6 and subsequent releases, but registered users will be 
  34.   able to obtain upgrades at very reasonable prices.  See ORDER.GET for 
  35.   additional pricing information.
  36.  
  37.   After the release date of Version 2.6, users sending in registrations
  38.   from the older versions still in circulation will receive both 2.5 
  39.   and 2.6 with documentation on disk, but no printed manual.  Read 
  40.   the file README.DOC before printing out the Version 2.5 manual.
  41.  
  42.   Information regarding the display of the Copyright notice:  We have 
  43.   attempted to make it so the notice will be displayed once and only 
  44.   once at the first call to GET after the computer is booted.  GET 
  45.   checks the Environment block to determine whether it has been run
  46.   prior to the current call.  If there is a GET= or a G$$= variable 
  47.   in the Environment, the copyright notice will not be displayed.  
  48.   If neither of these variables is present, GET will display the 
  49.   copyright notice, and then will create a G$$= variable to keep
  50.   itself from displaying the notice subsequently.
  51.  
  52.   You can avoid the creation of the G$$= variable by ensuring that 
  53.   there is always a GET= variable in the Environment whenever GET is 
  54.   called.  This is not always easy to control, however.  Note that a 
  55.   timeout for GET C /Wn or GET S /Wn will result in no value for the 
  56.   Environment variable.  This is also true for GET S and GET Z[E] if 
  57.   the string to be put in the Environment is empty such as when nothing 
  58.   but a return has been pressed.  The G$$= variable takes only 7 bytes 
  59.   of Environment space, so it is probably easier to just let GET create 
  60.   it rather than trying to ensure there is always a GET= present.
  61.  
  62.   The runtime version does not display the copyright notice unless
  63.   it is called with no valid arguments.  The runtime version for 
  64.   registered users is approximately 5K in size.
  65.  
  66.   New and modified features.
  67.   ---------------------------------------------------------------
  68.   The GET command information below is arranged alphabetically 
  69.   according to the GET command character. But first, a discussion
  70.   of new and changed switches and a few miscellaneous items.
  71.  
  72.   Switches.
  73.   -----------------------------------------------------------------
  74.   The #num syntax is eliminated along with the surrogates that have 
  75.     been replaced by the /X, /E, and /C switches.  #num and its ilk 
  76.     are all replaced with /Wnum.  The extended, enhanced, and break
  77.     surrogrates are all replaced with the switches that were intro-
  78.     duced in Version 2.5.  The older syntax was supported in 2.5 for
  79.     compatibility, but will no longer work in 2.6.
  80.  
  81.   $num indicates that num is in Hexadecimal if a number is expected.
  82.     This is useful for GET R and GET B, and can be used any place a 
  83.     numerical arg or parameter is expected.
  84.  
  85.   Now the # sign works as a prefix to an ASCII character and means use 
  86.     this character as a number.  Thus you can perform arithmetic using 
  87.     the numerical value of ASCII characters.  The # character, like the 
  88.     $ character for hex, can be used wherever numerical input is 
  89.     expected; however, with the # character only one character 
  90.     immediately following it is converted to the ASCII value of that 
  91.     character.  These conversions will be most useful with GET R.
  92.  
  93.   The /~ switch for GET S is being phased out, and replaced by /X (for 
  94.     Xcape).  The operation of GET S with the /X switch has been 
  95.     enhanced.  When /X is specified, if the user presses Escape, the 
  96.     Escape surrogate will be the result, and if the user presses Return 
  97.     (Enter) before pressing any other keys, the CR surrogate will be 
  98.     the result.  A timeout will produce a 0 (zero) result.  If /X is 
  99.     not specified, all three of these user actions will produce a 0 
  100.     result.
  101.  
  102.   /H provides a generalized Hexadecimal capability.  Whenever numerical 
  103.     output is expected in the Environment, /H will convert the output 
  104.     to Hexadecimal.  For GET F, /X will still report the full filesize 
  105.     in hex even if the errorlevel is in kilobytes (/A not being used), 
  106.     while /H will report kilobytes in hex unless /A is being used.
  107.  
  108.   /N is a new switch to suppress the carriage return after a prompt.
  109.     This works with any command that issues a prompt, including ECho
  110.     (GET EC).  Use with caution.  If the prompt is on the bottom
  111.     line of the screen and the /A switch is being used, DOS may pick
  112.     up the prompt attribute as the new screen attribute as it scrolls.
  113.     Various video BIOS's may produce different results.
  114.  
  115.   The /T (Trim) switch by itself (not /TR or /TL) will trim both left
  116.     and right.  You can also use /TB to trim both.  Trim will now also
  117.     trim Alt-255 characters (as upper case spaces).
  118.  
  119.   /R, a new switch, will force the Return Code into the Environment for
  120.     any GET command instead of the normal Environment result.
  121.  
  122.     EXAMPLE: Use GET to estimate the number of minutes it will take to 
  123.     transfer a file at different transmission speeds.  Since the /Wdiv 
  124.     switch for GET F only affects the ErrorLevel, we can use /R to put
  125.     the resulting value in the Environment also.  However, the divisor
  126.     would be too large at 9600 and 14400, so some preliminary math is 
  127.     used in the 9600 and 14400 calculations.  To keep it simpler, no
  128.     adjustments are made if the file is larger than 655360.
  129.  
  130.     @echo off
  131.     if "%1"=="" goto HELP
  132.     Rem Get file size in bytes, store in SIZE=
  133.     GET F %1 /VSIZE= /A 
  134.     if "%SIZE"=="" GOTO NOTFOUND
  135.     if "%SIZE%"=="*" GOTO TOOBIG
  136.     echo Minimum transfer time for a file size of %SIZE%
  137.     GET F %1 /r /w7200 /a
  138.     echo  at 1200 bps = %GET% minutes
  139.     GET F %1 /r /w14400 /a
  140.     echo  at 2400 bps = %GET% minutes
  141.     Rem Get file size in Kilobytes (*1024)
  142.     Rem SIZE/1060*60 ≈ SIZE/1024*62
  143.     GET F %1 /W62 /R
  144.     echo  at  9600 bps = %GET% minutes
  145.     Rem SIZE/1650*60 ≈ SIZE/1024*97
  146.     GET F %1 /W97 /R
  147.     echo  at 14400 bps = %GET% minutes
  148.     GOTO END
  149.     :NOTFOUND
  150.     Echo File %1 not found. 
  151.     GOTO HELP
  152.     :TOOBIG
  153.     Echo File %1 is too large.  Max size is 655360.
  154.     :HELP
  155.     Echo   The argument (%%1) is a file specification
  156.     Echo   bps = bits per second, cps = characters per second
  157.     Echo   for 12-2400, we use 10 bits / character (8 + start + stop)
  158.     Echo   for v.32, we est  8-9 bits / character
  159.     Echo   therefore
  160.     Echo      1200 bps = max of  120 cps
  161.     Echo      2400 bps = max of  240 cps
  162.     Echo      9600 bps = est of 1000-1100 cps, use est 1060
  163.     Echo     14400 bps = est of 1600-1700 cps, use est 1650
  164.     :END
  165.     SET SIZE=
  166.     SET GET=
  167.  
  168.  /S, a new switch for sound control, has been added.  For this
  169.    release, the only effective format is either /S or /S0 to turn
  170.    off the beeps for various alerts, such as striking an invalid
  171.    key, or getting a time-out.
  172.  
  173.  A revised method for locating the master environment for the /M 
  174.    switch has been implemented.  It is hoped that this will work in
  175.    those few instances where the old method failed.  Testing with
  176.    DESQview indicated that it would work with MS DOS but not with
  177.    DR DOS.  However, when it works, it finds the Environment for
  178.    the original command processor that loaded DESQview, not for 
  179.    any command processors running in the DV window.  It might 
  180.    work similarly with Windows, but it hasn't been tested.
  181.  
  182.   The maximum length of the input string for GET S and GET ZE has 
  183.     been increased from 79 to 127.
  184.  
  185.   /W is now defined to be the same as /W0.  This has implications for
  186.     functions such as C, S, N, W, and R.  See GET R below.
  187.  
  188.   When numerical input is used for an argument or with /W, the 
  189.     numbers can now be as large as 65535.  Previously they were 
  190.     limited to 4 digits.
  191.  
  192.   Miscellaneous features:
  193.   ---------------------------------------------------------------
  194.   All waiting periods should work for Windows DOS multitasking.
  195.    The DOS "idle interrupt" is called to permit multitasking in 
  196.    these environments.  It has always worked in DESQview and OS/2
  197.    DOS sessions.
  198.  
  199.   The help screen can exit at the --More-- pause.  It will time out in 
  200.    10 seconds and go to the next screen.  Press Esc to exit at this 
  201.    point, or any key except space, CR, or Esc to cancel the timeout.
  202.    PgUp can be used to return to the first screen and start over.
  203.  
  204.   If a value is too large for the division method used to convert it 
  205.     to an Environment variable, only a single asterisk will be stored 
  206.     as the Environment value instead of adding an asterisk to an 
  207.     invalid value.  The asterisk means that the value is larger than 
  208.     655,530.  Previously the values stored were not very meaningful, 
  209.     and the new method makes it easier to test for a large value.
  210.  
  211.   When a character argument (the arg not in double quotes) is called 
  212.     for, it can now be enclosed in single quotes ("'"s, apostrophes). To 
  213.     include a single quote in the argument, use two apostrophes next to 
  214.     each other.  There must always be an even number of quote symbols.  
  215.     '' by itself is the same as no argument at all.  To specify exactly 
  216.     one quote and nothing else use ''''.  Quoting permits including a space 
  217.     in the argument for GET C, for example.  Since you cannot test for a 
  218.     space with IF, if user enters space it will be reported as ASCII 
  219.     255 unless /L is used.  A quoted argument can be useful with GET # 
  220.     below. The single quote is usually on the same key with the 
  221.     double quote character, and should not be confused with the grave
  222.     accent or "back quote" character which is often on the same key
  223.     as the tilde.
  224.  
  225.   Also removed is the error message if a version of DOS less than
  226.     2.0 is detected.  This is considered to be a highly unlikely
  227.     event, so it will result in simply the "Invalid command" message.
  228.     Some features of Version 2.6 require DOS 3.0 or later.
  229.  
  230.   GET COMMANDS in ASCII alphabetical order.
  231.  
  232.   GET #[E]                         Locate a substring in a string
  233.   ---------------------------------------------------------------
  234.     GET # is like the BASIC INSTR (In String) function.  It locates the
  235.     position of a substring within a string.  The syntax is:
  236.  
  237.     GET # "string" 'sub' [/Woffset] [/x] [/Trim]
  238.  
  239.     /x starts the search at the end of the string from right to left.  
  240.     The substring comparison is still left to right, and the position
  241.     reported is the offset from the beginning of the string.
  242.    
  243.     The result is 0 (zero) if the substring is not found in the 
  244.     string, else it is the location starting with 1 for the leftmost
  245.     character.  If no 'sub' is given, the length of string will be 
  246.     reported.  If /Woffset is specified, the search will begin at the
  247.     offset specified; thus, a second or subsequent occurrence can be
  248.     found.  If /x is specified, the offset is counted from right to
  249.     left.  The search is case sensitive.
  250.  
  251.     Notes: for GET # you cannot include the single quote character 
  252.     (apostrophe) in the substring.  
  253.  
  254.     Examples: Command                            Result
  255.     GET # "D:\subdir\filename.ext" '\'             3
  256.     GET # "D:\subdir\filename.ext" '\' /w3        10
  257.     GET # "D:\subdir\filename.ext" '\' /x         10
  258.     GET # "D:\subdir\filename.ext" '\' /x/w10     10
  259.     GET # "D:\subdir\filename.ext" '\' /x/w13      3
  260.  
  261.   GET #E uses the GET # arguments to Extract the string.
  262.     After skipping /Wn characters, the substring up to but not 
  263.     including 'arg' will be extracted.  The ErrorLevel is the length
  264.     of the extracted substring.
  265.  
  266.     If /X is specified, the substring in 'arg' plus everything to the
  267.     right except the first character  will be extracted.  On the 
  268.     basis that it is easier in BATch files to catenate strings rather 
  269.     than shorten them, the first character of the target string is 
  270.     likely to be a delimiter of some sort, for example the '\' in a 
  271.     filespec, or the white space between words.  The below 
  272.     examples demonstrate how easy it is to extract portions of a 
  273.     filespec.
  274.  
  275.     Examples: Command                            Result            ErrorLevel
  276.     GET #E "D:\subdir\filename.ext" ':'          D                      1
  277.     GET #E "D:\subdir\filename.ext" '\'          D:                     2
  278.     GET #E "D:\subdir\filename.ext" '\' /w3      subdir                 6
  279.     GET #E "D:\subdir\filename.ext" '\' /x       filename.ext          12
  280.     GET #E "D:\subdir\filename.ext" '.' /x       ext                    3
  281.     GET #E "D:\subdir\filename.ext" '\' /x/w10   filename.ext          12
  282.     GET #E "D:\subdir\filename.ext" '\' /x/w13   subdir\filename.ext   19
  283.  
  284.     Note:  There may be a confusing difference between the use of /Wn 
  285.     for GET Z[E] and GET #E.  For GET Z /Wn specifies the maximum width.
  286.     For GET # /Wn specifies the offset to start the extraction.  In 
  287.     retrospect it would seem to be better to reverse the meaning of 'arg" 
  288.     and /W for GET Z[E], but this would make it incompatible with the
  289.     previous release.
  290.  
  291.     The /T trim switches can be used to trim blanks and Alt-255 
  292.     characters from either or both ends of the extracted string.
  293.  
  294.  
  295.   GET 4, GET DV                        4DOS and DESQview Versions
  296.   ---------------------------------------------------------------
  297.   DESQview and 4DOS Version numbers.  GET DV reports the DESQview 
  298.     Version number if it is running, otherwise 0.  GET 4 reports
  299.     the 4DOS Version number if it is running, otherwise 0.  The 
  300.     4DOS Version number only indicates that 4DOS is in memory, not
  301.     necessarily that it is the parent of the BATch program, but you
  302.     can check for that with the test given in the 4DOS manual:
  303.       if not "%_cwd%"=="" echo 4DOS is loaded!
  304.  
  305.   GET AE                                           ROM BIOS Model
  306.   ---------------------------------------------------------------
  307.   GET AE returns additional information in the Environment.  In 
  308.     addition to the 2-byte machine code, there is a space, then the
  309.     8-byte BIOS date.
  310.  
  311.   GET B                              Blank Screen [using a color]
  312.   ---------------------------------------------------------------
  313.   GET B can now use the same attributes with /A that the prompt uses.
  314.     The /W switch can be used with GET B to set the number of roWs 
  315.     on the screen for EGA or VGA monitors.  GET B /W25 sets the
  316.     screen to 25 line mode.  GET B /W43 sets EGA screens to 43 line
  317.     mode, and VGA screens to 50 line mode.  If the /X switch is used,
  318.     GET B will return the current number of lines on the screen 
  319.     instead of the video attribute.  This is done by using a BIOS
  320.     call to load either the default 8x14 or 8x8 font table.  Your
  321.     number of lines may vary depending on your EGA or VGA BIOS. To
  322.     get 25 line mode, it may work better to use GET V 3 to set video
  323.     mode 3 instead of GET B /W25.
  324.  
  325.     GET BE will still work the same, and the number will be taken to 
  326.     be in hex whether it has a $ or not with the Environment value in
  327.     hex.  GET B can take a $hex number as input but will report in decimal 
  328.     unless /H is used.
  329.  
  330.   GET D                                               DOS Version
  331.   ---------------------------------------------------------------
  332.   GET D now puts 20 in the Environment for OS/2 major version.  Also,
  333.   GET DE will put a 2 digit minor in Environment (but not in ErrorLevel).
  334.  
  335.   GET E                                         Environment Space
  336.   ---------------------------------------------------------------
  337.   Information about the Environment space with GET E has been enhanced 
  338.    to provide the full size as an eXtra function with /X.  GET E or 
  339.    GET EE with the /X switch will report the total bytes in the 
  340.    command processors Environment.  If you are running under a 
  341.    secondary command processor, GET E or GET EE with the /M switch 
  342.    will report Environment information for the master Environment.
  343.  
  344.    One way to use this information is to be able to enlarge the 
  345.    Environment space available if GET E reports too little to do what 
  346.    you want to do.  For example, suppose you need 100 bytes of 
  347.    Environement free, but GET E tells you there are only 50 bytes 
  348.    available.  You can then find the total size of the Environment, 
  349.    and recursively invoke the command processor with the new size
  350.    that you will need after finding out how big it was originally.
  351.    
  352.    EXAMPLE: You need 100 bytes of Environment free:
  353.  
  354.    GET E
  355.    Rem First time GET reports ErrorLevel : 50
  356.    Rem Then the second time through with enough space branch to CONTINUE
  357.    IF ErrorLevel 100 goto CONTINUE
  358.    GET E /X
  359.    Rem Check for error to prevent infinite loop.
  360.    IF not ErrorLevel 1 GOTO END
  361.    Rem Add 112 bytes to original Env size. (use a multiple of 16).
  362.    GET R "+" %GET% /W112
  363.    Rem Invoke a new command processor with increased Env and run BAT file.
  364.    %COMSPEC% /E:%GET% /C%0 %1 %2 %3 %4 %5
  365.    Rem When the secondary command processor terminates, it will have
  366.    Rem   run this BATch file, so now we must exit.
  367.    GOTO END
  368.    :CONTINUE
  369.    Rem Do your thing here.
  370.    :END
  371.  
  372.   A subtle change in the operation of GET E that may be useful.  
  373.     Previously, it did not remove the GET variable from the 
  374.     Environment before measuring the space remaining, even though it
  375.     overwrote it later with the new GET variable.  Now it will 
  376.     remove the GET or other variable specified with /V for GET E 
  377.     before measuring.  That gives a better measure of how much space 
  378.     is available for GET variables.  To make it work as it did before, 
  379.     just specify a variable that is not already in the Environment 
  380.     with the /V switch. As usual, /V- will suppress any changes to
  381.     the Environment.
  382.  
  383.     For the old method it would have been necessary to call GET twice
  384.     or remove any existing GET variable from the environment with 
  385.     SET GET= to get a more accurate measure of the Environment space
  386.     available for GET to work in.  To provide for sufficient free
  387.     Environment space in the event the BATch file is being run from
  388.     a "shell" you can now SET GET=(a large variable) in your AUTOEXEC or 
  389.     before loading the shell (PC Shell, Xtree, etc.), and when GET 
  390.     measures the environment it will clear out the GET variable and 
  391.     give you an accurate reading.
  392.  
  393.   GET EC                                    Echo [with attribute]
  394.   ---------------------------------------------------------------
  395.   An "echo" feature was added.  This can be effected by calling GET EC
  396.     with a "prompt" such as: GET EC "Hello".
  397.     The advantages to using this instead of GET I "Hello" for example,
  398.     are that the echo feature can be redirected. The ending carriage
  399.     return can be suppressed with /N.  If you want to Echo a printer
  400.     command, for example, you can do it with GET EC "Esc command">PRN /N.
  401.     An ANSI.SYS command can be echoed with GET EC "Esc command" /N
  402.  
  403.   GET F                                    File Size or Date/Time
  404.   ---------------------------------------------------------------
  405.   GET F can now return the File DATE and/or TIME. This feature has
  406.     been requested by quite a few users so was added to this release at
  407.     the last minute. The syntax is:
  408.  
  409.     GET F[E] filename /E [/Wn]
  410.  
  411.     The /E switch specifies that GET F return the date instead of the
  412.     file size.  The number n in /Wn uses the same coding as GET H to 
  413.     return the date/time information; i.e. 2=Day of the Month, 4=Month,
  414.     8=Year, 16=Minute, and 32=Hour. These are the only valid codes.
  415.     The default is 2 for Day of the month. In other respects,
  416.     GET F[E] /E works the same as GET H[E] for reporting the date 
  417.     information, and the format will be the same as for system date/
  418.     time information as reported by GET H.  International date/time
  419.     formats have not been implemented in this version, but will be in
  420.     a future version.
  421.  
  422.     NOTES: Previously GET F /E worked the same as GET F /X.  This has
  423.     been changed and any BATch programs that used GET F /E must be
  424.     changed to use GET F /X instead.
  425.  
  426.     GET F does not open a subdirectory as a file and therefore cannot 
  427.     obtain the date of a subdirectory.  For GET F ... /E, if the filespec
  428.     is a subdirectory, the ErrorLevel will be 0 and the Environment variable
  429.     will be empty.  Root directories will probably return the same 
  430.     result, but see information on root directories below.
  431.  
  432.     GET F filespec /A is for small files and reports the full size in the
  433.     Environment, and in the ErrorLevel (max 255) unless reduced by /Wdiv.
  434.  
  435.     For GET F, /X will still report the full filesize in hex even if
  436.     the errorlevel is in kilobytes (/A not being used), while
  437.     /H will report kilobytes in hex unless /A is being used.  Sorry 
  438.     if this is a bit confusing.
  439.  
  440.     GET F must open the file for reading in order to obtain the 
  441.     requested information.  This means that GET F may fail on files 
  442.     that cannot be opened in this manner.  Although special handling 
  443.     is implemented for directories (which GET cannot open as files), 
  444.     there are other cases where GET may return the code 5 meaning 
  445.     "Access denied".  Such cases include, but may not be limited to
  446.     files on network drives for which read access has not been 
  447.     granted, files opened by other processes, volume label names, and 
  448.     possibly root directories in older versions of DOS.  The 
  449.     following return codes are of particular interest for GET F.
  450.         2 for "File not found"
  451.         3 for "Path not found" (this may also be returned for an
  452.                                 invalid drive specification).
  453.         5 for "Access denied"
  454.        15 for "Invalid drive"
  455.  
  456.   GET F will accept a root directory specification and treat it the 
  457.     same as a subdirectory by reporting an ErrorLevel of 0 and setting 
  458.     the Environment variable to 0 also.  However, since the root 
  459.     directory is not a file, the result may be dependent on the version 
  460.     of DOS.  It has only been tested with MS-DOS 5.0 and may work 
  461.     differently on older versions of DOS.  If your application may 
  462.     sometimes use GET F for a root directory, test it with all versions 
  463.     of DOS that it may encounter to determine the results that will be 
  464.     reported.  If an invalid drive is specified in the filespec, the
  465.     ErrorLevel will probably be 3 (path not found) and the Environment 
  466.     variable will be empty.  Remember that GET F does not check for a
  467.     valid disk in the drive, so if you are checking A: or B: and 
  468.     there is a chance that there may not be a formatted diskette in 
  469.     the drive, use GET K, Q, or L first to verify it.  Checking for
  470.     a formatted diskette each time would slow GET F down with the
  471.     extra overhead which is unnecessary in most cases.
  472.  
  473.     GET F will also accept the \ as the last character of the filespec if 
  474.     it is a directory.  A trailing \ will be ignored, so it doesn't 
  475.     necessarily specify a directory. For a root directory, the \ is
  476.     required.
  477.  
  478.   GET H                                      System Date and Time 
  479.   ---------------------------------------------------------------
  480.   GET HE has been changed to display a 4-digit year if code 8 is 
  481.     included in the argument.  This permits years later than 1999 to 
  482.     be reported and used.   Note: 4DOS Version 3.xx DATE command will 
  483.     not accept a 4-digit year.  4DOS Version 4+ works OK.
  484.     The ErrorLevel for Year is Year-1900, thus 2000 will be 100, etc.
  485.  
  486.     The code 256 was added to specify the result to be 100ths of seconds 
  487.     Code 256 works only with H, not HE (as does code 128).  
  488.  
  489.     GET HE now will check for a /A switch, and if found will not
  490.     substitute a leading blank for a leading 0.
  491.  
  492.     EXAMPLE: Display the Day of The Week for any date between 
  493.     1-1-1980 and 12-31-2099, then reset the current date.
  494.  
  495.     @echo off
  496.     set TRY=%1
  497.     if not "%1"=="" goto TryDate
  498.     get s "Enter mm-dd-yyyy: " 99-99-9999 /VTRY=
  499.     :TryDate
  500.     GET HE 14 /vDAY=
  501.     date %TRY%
  502.     GET H 1
  503.     date %DAY%
  504.     goto DAY%GET%
  505.     :DAY6
  506.     set DOW=Satur
  507.     goto END
  508.     :DAY5
  509.     set DOW=Fri
  510.     goto END
  511.     :DAY4
  512.     set DOW=Thurs
  513.     goto END
  514.     :DAY3
  515.     set DOW=Wednes
  516.     goto END
  517.     :DAY2
  518.     set DOW=Tues
  519.     goto END
  520.     :DAY1
  521.     set DOW=Mon
  522.     goto END
  523.     :DAY0
  524.     set DOW=Sun
  525.     :END
  526.     Echo Day of the week for %TRY%: %DOW%day
  527.     :EXIT
  528.     Set TRY=
  529.     Set DAY=
  530.     Set DOW=
  531.     Set GET=
  532.     
  533.   New waiting time features in GET H!
  534.   GET H (Horological) /W option revised.
  535.  
  536.    /Wnum now means wait for the given number of seconds, then report.
  537.    /X/Wnum means wait until a minute in 24 hour time, then report.
  538.      NOTE: The 24 hour time specification must be in military format,
  539.      no punctuation; e.g., 1135, 0300, 1056, etc.  Use 2400 for 
  540.      midnight, not 0000.
  541.    
  542.   In either case the wait cannot be longer than 18 hours (65535 
  543.     seconds).  If the 24 hour time is longer than 18 hours hence,
  544.     it will be reduced to 18 hours.  If a number of seconds greater 
  545.     than /W65535 is specified, the results are unpredictable.  If the 
  546.     24 hour time specification is less than the current time, it will
  547.     be interpreted as meaning going past midnight to the given time 
  548.     on the next day.  Internally GET C is used to process the waiting 
  549.     time, thus the wait can be interrupted by pressing any key.  If a 
  550.     "prompt" is included, it will be displayed during the wait.  Any 
  551.     switches will be used for GET C also, thus /A can be used to 
  552.     control the attribute of the prompt.  However, no character 'arg' 
  553.     will be recognized, so any key will interrupt the wait.
  554.  
  555.   Although it was possible to accomplish the same thing with GET C /W 
  556.    in previous versions, this feature will make it easier and more 
  557.    precise to specify waiting times in BATch files.  If necessary to 
  558.    wait more than 18 hours, more than 1 call to GET can be used to wait 
  559.    various lengths of time, each no more than 18 hours.
  560.    
  561.   EXAMPLES:
  562.    1. Wait until 11:30 p.m. the same day.
  563.  
  564.    GET HE "Waiting until 2330" 112 /x /w2330
  565.    Rem the prompt is displayed while waiting.
  566.    Rem Waiting until 2330
  567.    REM After the appropriate wait the results of GET HE 112.
  568.    The Environment is: 23:30:00
  569.    The ErrorLevel is: 8
  570.  
  571.    2. Wait until 3 a.m. the next day (or the same day if after midnight)
  572.  
  573.    GET HE 112 /x /w300
  574.    The Environment is: 03:00:00
  575.    The ErrorLevel is: 8
  576.  
  577.    3. Wait for 3600 seconds (1 hour).  Starting time: 11:30 a.m.
  578.    
  579.    GET HE 112 /w3600
  580.    The Environment is: 12:30:00
  581.    The ErrorLevel is: 8
  582.  
  583.   GET K,  GET L,  GET Q                      Disk Space and Label
  584.   ---------------------------------------------------------------
  585.   Commands GET K, Q, and L have been modified to use a different procedure 
  586.     to check for a formatted floppy disk in a drive.  This procedure is 
  587.     much faster if there is a disk in the drive that is not formatted.  
  588.     As before, if it cannot be determined if a formatted disk is in the 
  589.     drive, the ErrorLevel will be 0, and an error code will be in the 
  590.     Environment. The error codes that will probably be returned may be 
  591.     different than previous versions of GET as follows:
  592.  
  593.     1  Invalid drive specified - this new procedure works only for 
  594.        drives on the primary disk controller, usually A: and B:.
  595.     2  Address mark not found meaning disk is not formatted
  596.     6  Floppy disk has been removed.  If this code is returned, try 
  597.        again since it may persist even if the drive door has been
  598.        opened and closed again, especially if a disk cache is in use.
  599.    32  Controller failed meaning disk is not formatted.
  600.   128  Drive timed out probably because door is open
  601.  
  602.   Other codes that may be seen - test on your system:
  603.     3  disk write protected may mean no diskette in drive.
  604.     4  sector not found - possible if disk is not formatted.
  605.     8 and 9  DMA errors (unlikely)
  606.    12  media type not found - possible if disk is not formatted.
  607.    16  data error - formatted disk in drive but is unreadable
  608.    64  seek failed (unlikely) .
  609.  
  610.  
  611.   GET P                                            Printer Status
  612.   ---------------------------------------------------------------
  613.   Customized printer status tests.  GET P[E] will accept a
  614.     numerical arg representing a byte value.  This value will be
  615.     "and"ed with the printer status byte, and the result returned
  616.     in the ErrorLevel and the Environment.  If a numerical arg is 
  617.     present GET PE will not affect the status of PrtSC, but it
  618.     will still attempt to initialize the printer.  Note that if you
  619.     are using a print spooler or buffer, all bets are off.  Everything
  620.     depends on what is returned in response to Int 17h, Service 02.
  621.    
  622.     Printer status items that can be tested for.  Sum the values to 
  623.     test for the items desired.
  624.        Value Hex     Item
  625.          1    $1   Time-out
  626.          8    $8   I/O Error
  627.         16   $10   Printer selected
  628.         32   $20   Out-of-paper signal
  629.         64   $40   Acknowledgement from printer
  630.        128   $80   Printer not busy (0 means busy)
  631.  
  632.     For GET PE only, the /X switch will force disabling of PrtSc 
  633.     whether a printer is attached or not.
  634.     
  635.     EXAMPLES: 
  636.     1. GET P 255 will return a value representing the sum
  637.     of the values of all 1-bits in the printer status byte.
  638.  
  639.     2. GET P 144 will indicate with either 0 or 144 whether the 
  640.     printer is available and ready for data.
  641.  
  642.     3. Disable Shift-PrtSc:
  643.        GET PE /X
  644.        Enable Shift-PrtSc again but only if the PE test is 1:
  645.        GET PE
  646.  
  647.   GET R                                                'Rithmetic
  648.   ---------------------------------------------------------------
  649.   GET R ('Rithmetic) has the following new features.  The arithmetic 
  650.     symbol must be entered as the "prompt" argument.
  651.  
  652.     Syntax:  GET R ["+-*/!=#"] [num1] [/Wnum2] [/H]
  653.              The defaults for num1 and num2 are 0 (zero).
  654.              /H reports the final Environment result in Hexadecimal
  655.     Symbols: "+"  the default, adds the two numbers.
  656.              "-"  subtracts num2 from num1
  657.              "*"  multiplies the two numbers.  The maximum product is
  658.                   655,350.  If the multiplication produces a larger 
  659.                   product an asterisk will be used to
  660.                   indicate that the result is too large.
  661.                   Note num2 defaults to 0, so if it
  662.                   is not specified, the result will be 0.
  663.              "/"  divides num1 by num2 by integer arithmetic.  Only
  664.                   the quotient is returned.  See NOTE below.
  665.              "!"  modulo arithmetic.  Divides num1 by num2 and returns
  666.                   only the remainder.
  667.          NOTE:    Division by zero is invalid.  If num2 is omitted,
  668.                   or is 0, the result will be num1 for "/" or "!".
  669.                   If num1>255 the result will be num1 modulo 256.
  670.              "="  compares num1 and num2 and returns one of:
  671.                   0 if num1<num2
  672.                   1 if num1=num2
  673.                   2 if num1>num2.
  674.                   This makes it easy to use ErrorLevel to check for
  675.                   >= or <= as well as one of the above.
  676.  
  677.     When numerical input is used for an argument or with /W, the 
  678.     numbers can now be as large as 65535.  Previously they were 
  679.     limited to 4 digits.
  680.  
  681.     $num indicates that num is in Hexadecimal if a number is expected.
  682.     This is useful for GET R, GET B, and can be used anyplace a 
  683.     numerical arg or parameter is expected.
  684.  
  685.     Now the # sign works as a prefix to an ASCII character and means use 
  686.     this character as a number.  Thus you can perform arithmetic using 
  687.     the numerical value of ASCII characters.  The # character, like the 
  688.     $ character for hex, can be used wherever numerical input is 
  689.     expected; however, with the # character only one character 
  690.     immediately following it is converted to the ASCII value of that 
  691.     character.  These conversions will be most useful with GET R. GET R 
  692.  
  693.     /H provides a generalized Hexadecimal capability.  Whenever 
  694.     numerical output is expected in the Environment, /H will convert
  695.     the output to Hexadecimal. 
  696.  
  697.     The /A (for ASCII) switch in the case of GET R, means put the 
  698.     ErrorLevel in the Environment as an ASCII character.
  699.  
  700.     EXAMPLES: 
  701.     1. Convert a hexadecimal number to decimal
  702.     GET R $ABC
  703.     The Environment is: 2748
  704.     The ErrorLevel is: 188
  705.     NOTE: Since the ErrorLevel is limited to a max of 255, the result
  706.     is reported modulo 256.
  707.  
  708.     2. Add a hexadecimal number to a decimal number
  709.     GET R 10 /W$A
  710.     The Environment is: 20
  711.     The ErrorLevel is: 20
  712.  
  713.     3. Add a hexadecimal number to a decimal number, result in hex
  714.     GET R 10 /W$A /h
  715.     The Environment is: 14
  716.     The ErrorLevel is: 20
  717.  
  718.     4. You want a single digit for the month to use in 
  719.     constructing a filename.  Suppose the month is December.
  720.  
  721.     GET H 4 /H
  722.     The Environment is: C
  723.     The ErrorLevel is: 12
  724.  
  725.     5. Suppose you want a series of characters A, B, C, D, E to 
  726.     construct 5 filenames.  With the new methods only one call to
  727.     GET within the loop is necessary.
  728.  
  729.     Rem Establish starting point of first character - 1.
  730.     GET R "-" #A /W1 /VC= /A
  731.     Rem Convert the value for the last character.
  732.     GET R #E /VN=
  733.     :NAMELOOP
  734.     Rem Convert last char to num, add 1, and convert back to char.
  735.     GET R "+" #%C% /W1 /VC= /A
  736.     Echo Character %C% can be used in a name.
  737.     IF NOT ERRORLEVEL %N% GOTO NAMELOOP
  738.     SET C=
  739.     SET N=
  740.  
  741.     6. Convert a hexadecimal number to an ASCII Character
  742.     GET R $4F /A        
  743.     The Environment is: O
  744.     The ErrorLevel is: 79
  745.  
  746.     7. Add a hexadecimal number to an ASCII Character, and convert
  747.     the result to an ASCII character.
  748.     GET R #A /W$A /A
  749.     The Environment is: K
  750.     The ErrorLevel is: 75
  751.     
  752.     8. Add a hexadecimal number to an ASCII Character, result in hex
  753.     GET R #A /W$20 /h
  754.     The Environment is: 61
  755.     The ErrorLevel is: 97
  756.  
  757.   GET S                                                Get String
  758.   ---------------------------------------------------------------
  759.   GET S has additional Exit key features.
  760.  
  761.     When /X is specified, if the user presses Escape, the Escape 
  762.     surrogate will be the result, and if the user presses Return (Enter) 
  763.     before pressing any other keys, the CR surrogate will be the result.  
  764.     A timeout will produce a 0 (zero) result.  If /X is not specified, 
  765.     all three of these user actions will produce a 0 result.
  766.  
  767.     /E turns on function keys as Exit keys.  If the user presses
  768.     a function key (F1-F10 only), and if /E is specified, then the
  769.     surrogate code (100+scan code) for that function key will be 
  770.     reported.  /E includes /X, so both are not needed.  /E does not 
  771.     turn on Enhanced keys in this case, it only enables F1-F10.  
  772.     This permits something like "F1 for help" to be used.
  773.  
  774.   The /~ switch for GET S is being phased out, and replaced by /X (for 
  775.     Xcape).  If used with GET?=ON a warning will be displayed.
  776.  
  777.   The maximum length of the input string for GET S and GET ZE has 
  778.     been increased from 79 to 127.
  779.  
  780.   GET W                                            Warm/Cold Boot
  781.   ---------------------------------------------------------------
  782.   GET W will now take a prompt.  If a "prompt" is specified, the code 
  783.     for GET C is called to wait for a character to be entered.  The 
  784.     switches for GET C including /W, /C, and /A can be used.  If /C is 
  785.     not specified the user can break out with Ctrl-Break or Ctrl-C.  
  786.     To prevent this, use /C.  When a valid character is entered, the
  787.     specified type of reboot will be initiated.  Using a prompt 
  788.     nullifies the effect of an argument which modifies GET W to just
  789.     try to determine whether the last boot was warm or cold.  As with
  790.     GET C, if an invalid character is entered, the waiting time will
  791.     be infinite.
  792.  
  793.   GET X                     Return Code from Execution of Program
  794.   ---------------------------------------------------------------
  795.   GET X provides a method of getting the return code (ErrorLevel) from 
  796.     a program into the Environment.  The syntax is:
  797.    
  798.     GET X "d:\path\program.ext" ' progargs' [/switches]
  799.  
  800.     where "program" is the name of the program you want to run.  It 
  801.     must be fully qualified with drive, path, and extension of either 
  802.     .COM or .EXE (no BATch files).  The exceptions are if the program 
  803.     is on the current drive, or in the current directory, in which 
  804.     cases drive and\or directory will default to current.  Do not 
  805.     include any spaces inside the double quotes.  You can use .. for 
  806.     the parent directory of the current subdirectory, and . for the 
  807.     current directory, however the latter is not needed since it will 
  808.     default to the current directory.
  809.  
  810.     ' progargs' are the arguments, parameters, and switches for the 
  811.     program you want to run.  Many programs require that the first 
  812.     character in the "command tail" be a space, so it is good practice
  813.     to start the argument string with a space.  It is also good 
  814.     practice to enclose the progargs in single quotes, however if no
  815.     spaces are included, the quotes are not absolutely necessary.
  816.  
  817.     [/switches] are the optional switches for GET, such as /M for the
  818.     master environment, or /V to designate the variable name.  Any 
  819.     switches for the program must be included in progargs.
  820.  
  821.     If GET X is successfull in loading and running the designated 
  822.     program, the ErrorLevel from the program will be in both the 
  823.     Environment and the ErrorLevel when GET terminates.
  824.  
  825.     If GET X is not successful, the Environment variable will be 
  826.     empty, and the ErrorLevel will contain a reason for the failure:
  827.        2 File not found - check the file specifications.
  828.        3 Path not found - check the drive and path information
  829.        4 Too many open files
  830.        5 Access denied - check for proper .COM or .EXE extension
  831.        8 Not enough memory
  832.  
  833.     If the "child" program terminates abnormally, there will be no 
  834.     Environment variable, and the ErrorLevel will be one of the 
  835.     following:
  836.        21  Child program was terminated by Ctrl-C or Ctrl-Break.
  837.        22  Critical device error - e.g. answering "a" to "Abort, 
  838.            Retry, Fail".
  839.        23  Child program stayed resident as a TSR.  This should never 
  840.            happen because you should not load a TSR in this manner.
  841.  
  842.   GET XE places the eXecution path of GET.EXE in the Environment,
  843.     including the drive, path, name, and extension of the file and
  844.     location from which GET is executing.  The ErrorLevel will be the
  845.     ASCII code of the drive; e.g. 65 for A, 66 for B, etc.  This can
  846.     be useful on an installation disk to determine the drive from
  847.     which the installation program is running.  Requires DOS 3+.
  848.  
  849.  
  850.   GET Z                          Zap (Additional String Handling)
  851.   ---------------------------------------------------------------
  852.   GET Z.  The <skip> argument works for GET ZE as well as GET Z.
  853.     /X with GET Z[E] now means to extract from the right.  The skip
  854.     arg skips from right to left, and the /Wn takes n chars from that 
  855.     position. GET ZE works the same as GET Z now, except for the
  856.     source of the string.  Z takes the string from the "prompt", and
  857.     GET ZE takes the string from standard input.
  858.     NOTE: You can save the length of a string as an environment
  859.     variable with GET # above, or with GET Z with /R (see above).
  860.  
  861.     EXAMPLE: Extract the minutes and seconds from the DOS TIME 
  862.              command.
  863.     GET U 13
  864.     TIME >TIME.DOS
  865.     GET ZE 22 /W5 <TIME.DOS >NUL
  866.     NOTE: This is not a reliable method if any users might be using
  867.     DR DOS or 4DOS which have a different format for TIME and DATE.
  868.  
  869.   If you use GET Z or ZE with /W1 to extract a single character, the 
  870.     ASCII decimal value of the character will be in the ErrorLevel (or 
  871.     0 if the extraction failed).  Previously GET dutifully reported an 
  872.     ErrorLevel of 1 meaning that you extracted one character, but you 
  873.     already knew that so it wasn't very useful.  Reporting the value of 
  874.     the character provides additional information, and may save another 
  875.     call to GET to make that determination.
  876.  
  877.     Furthermore, for GET Z only, if both /W1 and /A (for ASCII) are 
  878.     specified, the ASCII decimal value will be spelled out in the
  879.     Environment also.  This allows it to be available to another BATch
  880.     command, or another GET command such as GET R.  If the extraction 
  881.     fails such as because the string is empty, or you skip too far, 
  882.     then the Environment variable will still be expunged.
  883.   -----------------------------------------------------------------------
  884.     If you have any questions, comments, or suggestions please contact us:
  885.         MOBY DISK: 1021 San Carlos Road, Pebble Beach, CA 93953
  886.     Phone: (408) 646-1899     COMPUSERVE:72357,2276      Prodigy: FNGC05A
  887.     Internet: bob.stephan@nitelog.com            BBS: Nitelog 408-655-1096
  888.     BBS: The Cricket 408-373-3773       /s/ Bob Stephan  December 22, 1993
  889.